An English version will follow.
❗ Pflicht
❕ Optional
Unter Linting versteht man das Durchführen einer statischen Code-Analyse. Diese soll sicherstellen, dass der Code einheitlich formatiert und somit von gewisser Qualität ist. Wenn man alleine an einem Projekt arbeitet, mag dies nicht von großer Bedeutung sein, aber für die Arbeit in einem Team ist dies unerläßlich. Denn nur so wird sichergestellt, dass alle Teammitglieder einheitlichen Code erzeugen. Quelle
Wir verwenden den Linter flake8
, welcher die PEP8-Standards überprüft.
❗ Installiere flake8
in deinem conda oder pip environment mit:
conda install flake8
oder
pip install flake8
❗ Aktiviere den Linter in deinem Editor, z.B. im VS Code:
Settings
❗ Die maximale line length soll 120 nicht überschreiten!
Die Zeilenlänge kannst du unter Settings
–> Python
–> Flake8 Args
anpassen, indem du auf Add Item
clickst und --max-line-length=120
eingibst.
Danach soll in deinem Editor angezeigt werden, wenn du etwas falsch formattierst, zum Beispiel:
❗ Imports sollen immer gruppiert im obersten Teil eines Moduls genannt werden, direkt nach Modul-docstrings und -kommentaren.
# Correct:
import os
import sys
# Wrong:
import sys, os
It’s okay to say this though:
# Correct:
from subprocess import Popen, PIPE
Mehr zu Imports: https://peps.python.org/pep-0008/#imports
❗ Dokumentiere deinen Code direkt, wenn du ihn schreibst. Im wesentlichen gibt es zwei Wege, wie man Code dokumentieren kann: docstrings und Kommentare.
Ein docstring ist ein string
, welches eine Klasse, eine Funktion oder ein Modul beschreibt. Beispiel (docstring in rot):
def multiply(a, b):
"""Multiplies the floats a and b.
Args:
a (float): First float
b (float): Second float
Returns:
float: result of the multiplication of a and b
"""
return a * b
Ein Kommentar kann an einem beliebigen Ort zum Beispiel innerhalb einer Funktion oder in einem Skript stehen und hilft den Entwickler*innen, den Code besser nachvollziehen zu können. Beispiel (Kommentar in grau):
# multiply two floats
a, b = 2.5, 3.0
product = multiply(a, b)
Um gute docstrings zu schreiben, solltest du dich an den folgenden Punkten halten:
❗ Generiere die docstrings automatisiert.
autoDocstring - Python Docstring Generator
von Nils Werner).google
aus (VS Code: clicke auf Settings
–> tippe docstring
ein –> setze Auto Docstring: Docstring Format
auf google
)Generate Docstring
ein neues, vorausgefülltes docstring einlegen❗ Fülle die vorausgefüllte docstrings VOLLSTÄNDIG aus.
Type
s von Argumenten angebenreturn
beschreiben❗ Auf einheitliche, konforme Beschreibungen achten
conda install -c conda-forge flake8-docstrings
oder
pip install flake8-docstrings
In VS Code, öffne Settings –> tippe flake8
ein und füge --docstring-convention=google
in das Feld Python > Linting: Flake8 Args
ein.
Jetzt hebt flake8 hervor, wenn du einen docstring falsch formuliert hast.
Ein Beispiel für eine gute Formulierung von docstrings ist:
def find_largest_distance(point, polygon):
"""Finds the largest distance between a point and the edges of a polygon.
Args:
point (shapely.geometry.Point): shapely point object
polygon (shapely.geometry.Polygon): shapely polygon object
Returns:
float: the largest distance between a point and the edges of a polygon
"""
distance_list = np.array([])
for poly_point in list(zip(*polygon.exterior.coords.xy)):
distance = point.distance(Point(poly_point))
distance_list = np.append(distance_list, distance)
max_distance = max(distance_list)
return max_distance
Warum?
type
von Args und return sind angegeben❕ Mehr zu google-docstrings: https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings
Type | Public | Internal |
---|---|---|
Packages | lower_with_under |
|
Modules | lower_with_under |
_lower_with_under |
Classes | CapWords |
_CapWords |
Exceptions | CapWords |
|
Functions | lower_with_under() |
_lower_with_under() |
Global/Class Constants | CAPS_WITH_UNDER |
_CAPS_WITH_UNDER |
Global/Class Variables | lower_with_under |
_lower_with_under |
Instance Variables | lower_with_under |
_lower_with_under (protected) |
Method Names | lower_with_under() |
_lower_with_under() (protected) |
Function/Method Parameters | lower_with_under |
|
Local Variables | lower_with_under |
❗ Verwende automatisierte Entfernung von Whitespaces nach Save: Settings
–> Files
–> Trim Trailing Whitespace
❕ Um Whitespaces hervorzuheben, kannst du die Erweiterung Highlight Trailing White Spaces
(Yves Baum) verwenden. Dies wird dir helfen, sauberen Code zu schreiben.
Themenspeicher: Design Patterns, Code - Struktur, DLR - Leitfaden, PEP 8, PEP 257 docstring